/ 
Webservice-Rosary-API-0.1.7
/ Webservice::Rosary::API

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 0 to disable caching. Default: 300. The random endpoint 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 avemaria commandline client for an example of using this in combination with curl to automatically download the .mp3 file.

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_error is enabled. An otherwise valid response that contains no MP3 link still dies 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/

https://www.discerninghearts.com/Devotionals/Rosary-Joyful-Mysteries.mp3
https://www.discerninghearts.com/Devotionals/Rosary-Luminous-Mysteries.mp3
https://www.discerninghearts.com/Devotionals/Rosary-Sorrowful-Mysteries.mp3
https://www.discerninghearts.com/Devotionals/Rosary-Glorious-Mysteries.mp3
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. The avemaria client uses this data to present each decade's Mystery title and Fruit of the Mystery during ordinary prayer mode; --fully additionally displays the longer meditation text supplied by the API. Invalid Mystery names return an empty string without making an HTTP request. Network and decoding failures are handled in the same way as day.

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:

/v1/list
/v1/date/:MMDDYY
/v1/novena
/v1/novena/:MMDDYY
/v1/54daynovena

THE avemaria UTILITY

The avemaria commandline Rosary client is installed with this distribution. It uses this API module for remote Rosary data, Webservice::Rosary::Stream for timed interactive text streaming, and Webservice::Rosary::Tradition for small pieces of traditional presentation metadata that are not supplied by the remote API.

Commandline options may continue to evolve as the prayer UX is refined.

Quick Start

With no arguments, avemaria selects today's Mystery and enters prayer mode:

avemaria

Prayer-oriented options may also be supplied without an explicit day or Mystery; today's Mystery is selected automatically. For example:

avemaria --scroll --color

An explicit day or Mystery without a prayer-mode option prints its Mystery summary instead:

avemaria Monday
avemaria Sorrowful

Valid day values are Sunday through Saturday. Valid Mystery names are Joyful, Sorrowful, Glorious, and Luminous.

Help and Background

avemaria help
avemaria --help
avemaria about
avemaria --about

help prints command usage. about prints background information about the Rosary.

MP3 Commands

The following commands print the full URL of the corresponding MP3 recording to STDOUT:

avemaria today
avemaria yesterday
avemaria tomorrow
avemaria random

This makes the command convenient to combine with another program, for example:

curl -O "$(avemaria random)"

Prayer Mode

The general prayer form is:

avemaria [DAY_OR_MYSTERY] [--pray] [--unceasingly]
         [--scroll] [--fully] [-i] [-t]
         [--sleep=0.N] [--speed=N] [--between=N]
         [--nocontrols]
         [--color [--dark | --light]]

--pray streams the selected Rosary prayer by prayer.

--unceasingly continuously repeats the same selected Rosary until the user stops it. It implies --pray, so these are both valid:

avemaria --unceasingly
avemaria --pray --unceasingly

Using both is intentionally redundant rather than an error. A completed Rosary starts again with its prayer and decade counters reset. The already loaded API data is reused rather than being unnecessarily fetched again, and live speed changes are retained between cycles.

Mystery and Intention Presentation

Mystery-set headings are displayed in uppercase. During prayer mode each new decade presents its individual Mystery title and its Fruit of the Mystery from the API. --fully additionally displays the longer meditation text for that decade.

The introductory intentions are local traditional presentation metadata rather than fields supplied by the remote API. The introductory Our Father is presented as being offered:

For the intentions and well-being of Pope Leo XIV.

The first three Hail Marys are presented for an increase in Faith, Hope, and Charity, respectively. These values are kept in Webservice::Rosary::Tradition rather than being represented as remote API data.

If the secondary Mystery-details request fails, avemaria warns and continues the basic Rosary instead of making the entire prayer unusable.

Scrolling and Reduced-Clutter Presentation

--scroll keeps previous prayer text visible instead of clearing the terminal between prayers. It is intentionally quieter than the non-scrolling display: the overall Mystery heading and live-control reminder are shown initially, and section headings are shown again when a new decade begins rather than before every individual prayer.

With --unceasingly --scroll, the overall heading is shown again when a new Rosary cycle starts, while ordinary repeated prayers remain uncluttered.

Without --scroll, the terminal is cleared as the client advances through the Rosary.

Detailed and Manual-Pacing Options

--fully

Adds the full decade meditation to the Mystery title and Fruit of the Mystery that are already shown in normal prayer mode.

-i

Requires <RETURN> after each prayer. When --fully is in use, the meditation presentation is also included in the manual pacing flow.

-t

Requires <RETURN> after each decade description. -t requires --fully.

Timing and Live Controls

The timing options are independent of presentation options:

--sleep=SECONDS

Sets the base delay before each streamed character. The default is 0.04 seconds. The value must be zero or greater.

--speed=MULTIPLIER

Sets the initial text-speed multiplier. The default is 1.0 and the value must be greater than zero. Live speed changes are relative to this starting value.

--between=SECONDS

Sets the pause between prayers. The default is 0.75 seconds and the value must be zero or greater.

--nocontrols

Disables the live single-key controls. -i and -t Return prompts still work. In --unceasingly --nocontrols mode, use Ctrl-C to stop.

When live controls are enabled and STDIN is interactive, the following keys are available while text is streaming and while timed waits are in progress:

SPACE or p   pause or resume
+ or =       speed up immediately
- or _       slow down immediately
0            reset to the initial --speed value
q            ask: Quit y/N?

A negative response to the quit prompt resumes the prayer. A confirmed quit restores the terminal, prints:

Pray the Rosary every day, +JMJ+

and exits successfully.

The terminal is also restored when the client handles SIGINT or SIGTERM, so interactive terminal mode should not be left altered after interruption.

Color

Color is strictly opt-in:

avemaria --color
avemaria --color --dark
avemaria --color --light

--color by itself uses the dark-background profile. --dark and --light are mutually exclusive and are meaningful only with --color. No color is emitted when --color is absent. Color is also suppressed for non-terminal output, TERM=dumb, or when the NO_COLOR environment variable is present.

The palette is organized by devotional role rather than applying arbitrary color to every line:

  • Hail Marys and the Joyful Mysteries use a light Marian blue.

  • Our Fathers use a subdued green.

  • Sorrowful Mystery headings use a dark red or maroon family.

  • Glorious Mystery headings use a warm yellow or gold family.

  • Luminous Mystery headings use a gentle violet or lavender family.

  • Each individual Mystery title is bold in the color of its Mystery family.

  • The Apostles' Creed, Hail Holy Queen, and the closing O God, Whose Only Begotten Son... prayer use a bold neutral treatment: near-white on the dark profile and near-black on the light profile.

The closing O God, Whose Only Begotten Son... prayer is folded to 72 columns for readability in the terminal.

Examples

Pray today's Rosary with the low-clutter scrolling presentation:

avemaria --scroll

Use the dark-background color profile (the default profile for --color):

avemaria --scroll --color

Use a light-background terminal profile:

avemaria --scroll --color --light

Pray the Sorrowful Mysteries with the full decade meditations:

avemaria Sorrowful --pray --fully --scroll

Pause after each decade description:

avemaria Friday --pray --fully -t

Repeat today's Rosary continuously until stopped:

avemaria --unceasingly --scroll --color

Option Composition

The options are intended to compose rather than define unrelated modes. --unceasingly controls repetition and implies prayer mode; --scroll only changes screen presentation; --fully controls meditation detail; the timing options control pacing; and the color options control styling. Consequently a command such as:

avemaria Luminous --unceasingly --scroll --fully --color --light --speed=1.25

has a straightforward meaning: repeatedly pray the Luminous Mysteries, preserve prior text, include full decade meditations, use the light-background color profile, and start at 1.25 times the normal text speed.

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:

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.

    https://drbo.org/cgi-bin/d?b=drb&bk=47&ch=6&l=9-13#x

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+