=================
Python Scriptures
=================

python-scriptures is a Python 2 and Python 3 compatible package and regular
expression library for validating, extracting and normalizing biblical
scripture references from blocks of text.

For more information, see http://www.davisd.com/projects/python-scriptures/

Typical usage is as follows::

    #!/usr/bin/env python

    >>> import scriptures
    >>> scriptures.extract('This is a test Rom 3:23-28 and 1 JOHn 2')
    [('Romans', 3, 23, 3, 28), ('I John', 2, 1, 2, 29)]

Range validation is performed automatically and invalid references are not
extracted.

    >>> import scriptures
    >>> scriptures.extract('Romans 3:23 is real, but Romans 2:30 is invalid.')
    [('Romans', 3, 23, 3, 23)]

Multi-Chapter references work:

    >>> import scriptures
    >>> scriptures.extract('You can specify a range of chapters like Rev 2-3')
    [('Revelation of Jesus Christ', 2, 1, 3, 22)]
    
References with single chapter books do not require the chapter be specified.

    >>> import scriptures
    >>> scriptures.extract('You can specify a single verse such as Jude 4')
    [('Jude', 1, 4, 1, 4)]
    >>> scriptures.extract('Or specify multiple verses with jude 2-5...')
    [('Jude', 1, 2, 1, 5)]


Installation
============

A setup script (setup.py) is provided.  To install, simply run the script with
the install command:

$ python setup.py install

Or just put the scriptures package somewhere on the Python path.


API
===

Return Values
-------------

When a "scripture reference" is returned, it is always a five value tuple
consisting of:

('Book name', start chapter, start verse, end chapter, end verse)


Functions
---------

There are four public functions exposed by this package.

extract
~~~~~~~

Extract a list of tupled scripture references from a block of text.

Arguments:

    text -- the block of text containing potential scripture references

Example:

    >>> import scriptures
    >>> scriptures.extract('This is a test Rom 3:23-28 and 1 JOHn 2')
    [('Romans', 3, 23, 3, 28), ('I John', 2, 1, 2, 29)]


reference_to_string
~~~~~~~~~~~~~~~~~~~

Get a display friendly string from a scripture reference.

Arguments:

    bookname -- the full or abbreviated book name

    chapter -- the starting chapter

Optional Arguments:

    verse -- the starting verse

    end_chapter -- the ending chapter

    end_verse -- the ending verse

Examples:

    >>> import scriptures
    >>> scriptures.reference_to_string('acts', 1)
    'Acts 1'
    >>> scriptures.reference_to_string('John', 3, 16)
    'John 3:16'
    >>> scriptures.reference_to_string('Rom', 3, 23, 3, 28)
    'Romans 3:23-28'
    >>> scriptures.reference_to_string('ecc', 1, 2, 2)
    'Ecclesiastes 1:2-2:26'

Single Chapter Book Examples:

    >>> import scriptures
    >>> scriptures.reference_to_string('jude', 1, 4)
    'Jude 4'
    >>> scriptures.reference_to_string('2john', 1, 4, 1, 7)
    'II John 4-7'


normalize_reference
~~~~~~~~~~~~~~~~~~~

Get a complete five value tuple scripture reference with full book name from
partial data.

Arguments:

    bookname -- the full or abbreviated book name

    chapter -- the starting chapter

Optional Arguments:

    verse -- the starting verse

    end_chapter -- the ending chapter

    end_verse -- the ending verse

Examples:

    >>> import scriptures
    >>> scriptures.normalize_reference('acts', 1)
    ('Acts', 1, 1, 1, 26)
    >>> scriptures.normalize_reference('John', 3, 16)
    ('John', 3, 16, 3, 16)
    >>> scriptures.normalize_reference('Rom', 3, 23, 3, 28)
    ('Romans', 3, 23, 3, 28)
    >>> scriptures.normalize_reference('ecc', 1, 2, 2)
    ('Ecclesiastes', 1, 2, 2, 26)


is_valid_reference
~~~~~~~~~~~~~~~~~~

Check to see if a scripture reference is valid.

Arguments:

    bookname -- the full or abbreviated book name

    chapter -- the starting chapter

Optional Arguments:

    verse -- the starting verse

    end_chapter -- the ending chapter

    end_verse -- the ending verse

Examples:

    >>> import scriptures
    >>> scriptures.is_valid_reference('John', 3, 16)
    True
    >>> scriptures.is_valid_reference('ecc', 1, 2, 2)
    True
    >>> scriptures.is_valid_reference('Romans', 2, 30)
    False
    >>> scriptures.is_valid_reference('Romans', 2, 20, 2, 29)
    True


Regular Expressions
-------------------

There are two compiled regular expression patterns exposed by this package.

book_re
~~~~~~~

Match a valid abbreviation or book name.

Examples:

    >>> import scriptures
    >>> import re
    >>> re.findall(scriptures.book_re, 'Matt test Ecclesiastes and 2 peter')
    ['Matt', 'Ecclesiastes', '2 peter']    


scripture_re
~~~~~~~~~~~~

Match a scripture reference pattern from a valid abbreviation or book name.

Examples:

    >>> import scriptures
    >>> import re
    >>> re.findall(scriptures.scripture_re, 'Matt 3 & Acts 1:2-3 Rev 2:1-3:2')
    [('Matt', '3', '', '', ''), ('Acts', '1', '2', '', '3'),
    ('Rev', '2', '1', '3', '2')]


Unicode
=======

This library is unicode compatible and recognizes the \u2013 en dash and \u2014
em dash.


Author
======

David Davis <[email protected]>
http://www.davisd.com