/ 
Bible-OBML-Gateway-2.01
River stage zero No dependents
/ Bible::OBML::Gateway

NAME

Bible::OBML::Gateway - Bible Gateway content conversion to Open Bible Markup Language (OBML)

VERSION

version 2.01

SYNOPSIS

use Bible::OBML::Gateway;

my $bg = Bible::OBML::Gateway->new;
$bg->translation('NIV');

my $obml_obj = $bg->get( 'Romans 12' );
print $bg->get( 'Romans 12', 'NASB' )->obml, "\n";

my $translations = $bg->translations;
my $structure    = $bg->structure('NASB');

DESCRIPTION

This module consumes Bible Gateway content and returns useful data-bearing objects or data structures. In the common case, it will accept a Bible reference and return a Bible::OBML object loaded with parsed content.

METHODS

The following methods are supported.

new

Instantiates a new gateway object. You can optionally pass a translation acronym to be used on subsequent requests.

my $bg = Bible::OBML::Gateway->new( translation => 'NIV' );

get

This method requires a text input containing a Bible reference that can be understood as a single chapter or single, unbroken run of verses. For example, "Romans 12" or "Ro 12:13-17" are acceptable, but "Romans 12:13-17, 19" is not.

You can optionally also provide an overriding translation. If not specified, the object's translation (set via the translation attribute) will be used.

The method will get the raw HTML content from Bible Gateway, parse it, and return a Bible::OBML object loaded with the data.

my $obml_obj = $bg->get( 'Romans 12' );
print $bg->get( 'Romans 12', 'NASB' )->obml, "\n";

Internally, all this method does is call fetch, pass that output to parse, and then load output that into a new Bible::OBML object.

fetch

If all you want to do is fetch the HTML from Bible Gateway, you can use this method. It uses the same signature as get and returns the returned raw HTML.

parse

This method requires source HTML like what you might get from a fetch call, which it will then parse and return a special sort of HTML that can be loaded directly into a Bible::OBML object via it's html method. (See Bible::OBML for more information.)

translations

This method will return a data structure consisting of data describing available translations on Bible Gateway per spoken language. It returns an arrayref containing a hashref per language. Each hashref contains an arrayref of translations, each represented by a hashref.

my $translations = $bg->translations;

This a simplified example of the data structure:

[
    {
        acronym      => 'EN',
        language     => 'English',
        translations => [
            {
                acronym     => 'NIV',
                translation => 'New International Version',
            },
        ],
    },
]

structure

This method will return a data structure consisting of data describing the structure of a given translation of the Bible from Bible Gateway. It can optionally be provided an overriding translation. If not specified, the object's translation (set via the translation attribute) will be used. The data structure returned is an arrayref of hashrefs, each representing a book.

my $structure = $bg->structure('NASB');

This a simplified example of the data structure:

[
    {
        testament    =>  'NT',
        display      =>  '2 John',
        osis         =>  '2John',
        intro        =>  0,
        num_chapters =>  1,
        chapters     =>  [
            {
                chapter => 1,
                type    => 'heading',
                content => [
                    "Walk According to His Commandments",
                ],
            },
        ],
    }
]

ATTRIBUTES

Attributes can be set in a call to new or explicitly as a get/set method.

my $bg = Bible::OBML::Gateway->new( translation => 'NIV' );
$bg->translation('NIV');
say $bg->translation;

translation

Get or set the current translation acronym. The default if not explicitly set will be "NIV".

say $bg->translation;
$bg->translation('NIV');

url

This provides access to the base URL, contained within a Mojo::URL object.

$bg->url( Mojo::URL->new('https://www.biblegateway.com/passage/') );

ua

This provides access to the Mojo::UserAgent user agent.

$bg->ua->transactor->name("Your Application's Name");

reference

This provides access to the Bible::Reference object used to parse and canonicalize Bible references.

$bg->reference->bible('Catholic');

Depending on which translation you get from Bible Gateway, you may need to alter the bible setting of reference, as in the example immediately above. By default, bible is set to "Protestant".

SEE ALSO

Bible::OBML, Bible::Reference, Mojo::URL, Mojo::UserAgent.

You can also look for additional information at:

AUTHOR

Gryphon Shafer <gryphon@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017-2021 by Gryphon Shafer.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)