NAME
Webservice::Rosary::API - Perl API client for the Rosary API at https://the-rosary-api.vercel.app and https://dailyrosary.cf.
SYNOPSIS
use v5.10;
use warnings;
my $Rosary = Webservice::Rosary::API->new;
my $mp3URL = $Rosary->mp3Link("random");
say $mp3URL;DESCRIPTION
This is an API client for https://the-rosary-api.vercel.app, which powers https://dailyrosary.cf*; the API requires no authentication, so the client here simply wraps most of the calls for convenient use in Perl programs.
It is meant to facilitate a couple of things. One is the generation of a full URL that may be used to download an audio file of the specified Mystery being said, as an .mp3 file. This means you may do something like what is done at https://dailyrosary.cf.
The second thing it is meant to do is to return the text of a full recitation of the Rosary, which is what the provided avemaria commandline utility uses to lead the user through the recitation of the specified Mystery.
For more information on the Rosary itself, please see the very end of this documentation.
The Rosary API is profiled at https://www.freepublicapis.com/the-rosary-api.
Contributed as part of the FreePublicPerlAPIs Project described at, https://github.com/oodler577/FreePublicPerlAPIs.
* - the module author is not affiliated with these sites
METHODS
new(param1 =$val1, ...)>-
Constructor. By default it creates an HTTP::Tiny user agent with a 10-second timeout and enables a small per-instance in-memory cache with a 300-second TTL. The following optional parameters are recognized:
ua-
An HTTP-compatible object providing
get. This is useful for testing and for applications that need to supply their own configured user agent. timeout-
Timeout used when constructing the default HTTP::Tiny instance. Default: 10.
cache_ttl-
Number of seconds successful responses may be served from memory. Set to
0to disable caching. Default: 300. Therandomendpoint is never satisfied from a fresh cache entry, so repeated random requests remain random. stale_if_error-
If true, a previously cached response may be used when the network request fails, even after its normal TTL has expired. Default: true.
cache-
Optional hash reference used as the per-instance in-memory cache. Most callers can leave this unspecified; supplying one is primarily useful for tests or for applications that want to inspect or preseed the cache explicitly. Cache contents are not written to disk and are not shared between objects unless the same hash reference is supplied to more than one object.
my $Rosary = Webservice::Rosary::API->new; my $NoCache = Webservice::Rosary::API->new(cache_ttl => 0); mp3Link("today" | "tomorrow" | "yesterday" | "random")-
Given the string describing when, returns the full URL of the MP3 recording reported by the API service.
my $Rosary = Webservice::Rosary::API->new; my $mp3URL = $Rosary->mp3Link("random"); say $mp3URL;See the
avemariacommandline client for an example of using this in combination withcurlto automatically download the.mp3file.Error Handling
Network failures, non-success HTTP responses, empty responses, and malformed JSON result in descriptive exceptions unless a stale cached response is available and
stale_if_erroris enabled. An otherwise valid response that contains no MP3 link stilldies after printing the known direct MP3 sources.MP3 Source Note
All recordings are actually freely available at the site,
https://www.discerninghearts.com/catholic-podcasts/holy-rosary/
day("Sunday" | "Monday" | "Tuesday" | ... | "Thursday" | "Friday" | "Saturday")-
Given the day, returns the Mystery of the Rosary traditionally associated with the day of the week. This module does include the Luminous Mysteries (associated with Thursdays*).
This method doesn't accept the name of a particular Mystery because this can be achieved using a look up table that maps each Mystery to a particular day, e.g.:
my $Convert = { luminous => "thursday", sorrowful => "friday", joyful => "saturday", glorious => "sunday", };Then the day of the week obtained via
$Convert-{$mystery}> can be used to derive the proper day to be used with this call.* - although, any Mystery may be said on any day
Error Handling
Invalid day names return an empty string without making an HTTP request. Network failures, HTTP errors, empty responses, and malformed JSON result in a descriptive exception unless stale-cache fallback is available.
details("joyful" | "glorious" | "sorrowful" | "luminous")-
Returns the detailed recitation data for the named Mystery, including the decade descriptions used by
avemaria --fully. Invalid Mystery names return an empty string without making an HTTP request. Network and decoding failures are handled in the same way asday.my $details = $Rosary->details("joyful"); clear_cache-
Empties the per-instance response cache and returns the object.
$Rosary->clear_cache;
Rosary API calls that are not currently supported:
THE avemaria UTILITY
The avemaria commandline Rosary client is installed with this module. The following is essentially verbatim from the client using the help command.
Note: Commandline options may change to accomodate feedback. This note will be removed once the cli UX settles.
Quick Start
> avemaria # no arguments
> ... runs through the recitation of the Rosary for today, equivalent,
to,
> avemaria $(date "+%A") --pray # `date` prints today's day of weekGetting Help
> avemaria help
> ... prints help sectionLearning More
> avemaria about
> ... prints an "about" sectionFunctional Commands
There are 2 types of functional commands. One set of commands returns a URL for an MP3, which may then be piped into another program to download it. The other set of commands displays the specified Mystery (by day of the week or actual name of the Mystery), so that the user may be guided through the specified Mystery of the Rosary - from start to finish.
Usage - to print MP3 URL to STDOUT:
avemaria [today | yesterday | tomorrow | random]Example 1
> avemaria today
> https://dailyrosary.cf/audio-rosary-sorrowful-mysteries.mp3Example 2
> curl -O \$(avemaria random) -w "\\nDownloaded file: %{filename_effective}\\n"
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 31.5M 100 31.5M 0 0 2374k 0 0:00:13 0:00:13 --:--:-- 5043k
Downloaded file: audio-rosary-sorrowful-mysteries.mp3
>Usage - to Pray the Rosary in the commandline:
avemaria DAY_OR_MYSTERY [--pray] [-i] [-t] [--fully] [--scroll]
[--sleep=0.N] [--speed=N] [--between=N]
Valid DAY_OR_MYSTERY values:
Joyful, Sorrowful, Luminous, Glorious, Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday
Optional flags:
--pray : automatically prints prayers character by character; default delay is 0.04 seconds.
-i : user must hit <RETURN> after each prayer (and description, if used with "--fully")
-t : user must hit <RETURN> after each description (requires --fully)
--fully : prints the full description of the current Mystery's Decade, including the Fruit of the Mystery
--scroll : keeps prior prayers visible instead of clearing the terminal between prayers
--sleep : base delay before each new character is printed. Default is 0.04 seconds.
--speed : initial text speed multiplier. Default is 1.0.
--between : pause between prayers, in seconds. Default is 0.75.
--nocontrols : disables live keyboard controls.
While --pray is streaming in an interactive terminal:
SPACE/p : pause or resume
+ or = : speed up immediately
- or _ : slow down immediately
0 : reset to the initial --speed valueExample 3
Used without options, it just prints the name of the Mystery
> avemaria Monday
> Monday - The Joyful Mysteries
>
> avemaria Sorrowful
> Friday - The Sorrowful Mysteries
>Example 4
> avemaria Friday --pray -t --fully
> .. clears screen, the plays the specified Mystery (Sorrowful in this case),
while pausing only at the beginning of each Mystery after the description has
been printed.Example 5
Run with absolutely no subcommands or flags, runs "--pray" for today's Mystery,
> avemaria
> .. clears screen, the plays the specified Mystery for today ...ENVIRONMENT
There is no set up other than a working Perl environment and required modules.
BUGS AND SUPPORT
Please report bugs to the Github issue tracker; also report back how to improve this library and the commandline utility:
https://github.com/oodler577/p5-Webservice-Rosary-API/issues
BACKGROUND ON THE ROSARY
The Rosary is a traditional Catholic prayer devotion that involves the repetition of prayers and meditation on key events from the lives of Jesus Christ and the Virgin Mary. The prayer is structured around a set of beads, each representing a specific prayer. These include the Our Father, Hail Mary, and Glory Be, which are recited while reflecting on the Mysteries-twenty key moments in the lives of Jesus and Mary, grouped into four categories: the Joyful, Sorrowful, Glorious, and Luminous Mysteries. The Rosary is both a contemplative prayer and a way to focus on the essential aspects of the Catholic faith, helping the faithful deepen their relationship with God.
The history of the Rosary dates back to the Middle Ages, with its roots often linked to St. Dominic, who is traditionally credited with receiving the Rosary from the Virgin Mary in the 13th century. The Rosary evolved over several centuries. One of its early forms was connected to the Psalter of Our Lady, where the faithful would pray 150 Hail Marys, reflecting the 150 Psalms of the Old Testament. This practice was common among laypeople who could not read the Psalms themselves but still wanted to engage in a structured form of prayer. Over time, the Rosary's prayers and structure were refined, and by the 16th century, it became formally established by the Catholic Church as a central devotion, with the mysteries of the Rosary added to provide a scriptural basis for the prayers.
Biblical Foundations of the Hail Mary
For Catholics, the Rosary is a deeply meaningful prayer practice that helps them draw closer to God by reflecting on the pivotal moments of salvation history. Its biblical foundations are grounded in scripture, with the Hail Mary drawn from the Angel Gabriel's greeting to Mary in Luke 1:28 and Elizabeth's words in Luke 1:42.
The first part of the Hail Mary comes from Luke 1:28 and Luke 1:42 in the Douay-Rheims translation:
Luke 1:28
And the angel being come in, said unto her: Hail, full of grace, the Lord is with thee: blessed art thou among women.Luke 1:42
And she cried out with a loud voice, and said: Blessed art thou among women, and blessed is the fruit of thy womb.
These biblical words form the Angelic Salutation, which Catholics begin the Rosary with:
Hail Mary, full of grace, the Lord is with thee: blessed art thou
among women, and blessed is the fruit of thy womb, Jesus.The Second Part of the Hail Mary
The second part of the Hail Mary, which was added later to the prayer, invokes Mary's intercession. This part is drawn from the Catholic tradition and reflects the Church's desire for Mary's prayers to be a source of strength and protection for all the faithful. The second part reads:
Holy Mary, Mother of God, pray for us sinners, now and at the hour
of our death. Amen.This petition is based on Mary's role as Mother of God (as declared in Luke 1:43, when Elizabeth calls her the "Mother of my Lord") and her ongoing role as intercessor for the Church. It is the second part of the Hail Mary that Catholics use to seek her intercession, especially in times of trial.
https://drbo.org/cgi-bin/d?b=drb&bk=49&ch=1&l=43-#x
The Our Father
The Our Father comes directly from Jesus' teaching in the Gospel of Matthew 6:9-13:
Matthew 6:9-13
Thus therefore shall you pray: Our Father who art in heaven, hallowed be Thy name. Thy kingdom come. Thy will be done, on earth as it is in heaven. Give us this day our daily bread. And forgive us our trespasses, as we forgive those who trespass against us. And lead us not into temptation, but deliver us from evil.
By meditating on the Mysteries of the Rosary, Catholics invite the presence of Jesus into their lives, contemplating His birth, death, resurrection, and the role of Mary in His story. These meditations, grouped into the Joyful, Sorrowful, Glorious, and Luminous Mysteries, help to guide the faithful through the essential moments of Christ's life and His salvation work.
The Rosary as a Communal Devotion
The Rosary is seen not just as a personal prayer, but as a communal devotion that fosters a deeper understanding of God's love and a powerful means of seeking His intercession. It is often prayed in groups, in parishes, or even in families, helping to build unity within the faith community. Through its rich combination of prayer and meditation, the Rosary has become a beloved devotion for Catholics around the world, encouraging spiritual growth and reflection on the central mysteries of the Christian faith.
The importance of daily prayer of the Rosary was emphasized by Our Lady during the Apparitions at Fatima in 1917, where she specifically urged the children to "pray the Rosary every day" for peace in the world and for the salvation of souls, making it a call for all the faithful to embrace this prayer as a tool for spiritual strength and intercession. For more information on Fatima, look up, "the Miracle of the Sun."
LICENSE AND COPYRIGHT
This module and utility is released under the same terms as Perl/perl.
REQUEST FOR COMMENTS
I have no idea how this is going to be used, and the way someone says the Rosary tends to be highly personal; so please let me know what kind of "--pray" controls would be helpful.
AUTHOR
Brett Estrade <oodler@cpan.org>
+Deo Gratias+